<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en-ca"><head>
  <link rel="icon" type="image/png" href="/maps/favicon.png">
  <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
  
  <title>RunSnakeRun Python Hotshot Profile Viewer</title><link rel="stylesheet" type="text/css" href="toolkit.css">
  <meta name="author" content="Mike C. Fletcher"></head>
<body style="direction: ltr;">
<h1>RunSnakeRun<br>
</h1>
<p class="introduction">RunSnakeRun is a small GUI utility that allows
you to view (Python) cProfile or Profile profiler dumps in a sortable
GUI view. &nbsp;It allows you to explore the profiler information using
a "square map" visualization or sortable tables of data.<br>
</p>
<h2>Features</h2><p>RunSnakeRun is a simple program, it doesn't provide
all the bells-and-whistles of a program like KCacheGrind, it's intended
to allow for profiling your Python programs, and just your Python
programs. &nbsp;What it does provide:</p><ul><li>sortable data-grid views for raw profile information</li><ul><li>identity: function name, file-name, directory name</li><li>time-spent: cummulative, cummulative-per, local and local-per time</li></ul><ul><li>overall data-grid view</li><li>(all) callers-of-this-function, (all) callees-of-this-function views</li></ul><li>squaremap view of call tree</li><ul><li>size proportional to amount of time spent by the given parent in the given function</li></ul><li>squaremap view of packages/modules/functions</li><ul><li>size proportional to time spent in each package/module/function</li></ul><li>basic navigation (home, back, up)</li></ul><h2><a name="install"></a>Installation<br>
</h2>
<p>You will need to have all of wxPython, SquareMap and RunSnakeRun
installed to use RunSnakeRun. &nbsp;You may also need the
"python-profile" package for your platform, which provides the pstats
view.</p><p>You will likely want to use your platform wxPython package. &nbsp;If you already have Python setuptools installed (a.k.a. <a href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy_install</a>), you should be able to install the Python packages with:</p><pre>easy_install SquareMap<br>easy_install RunSnakeRun<br></pre><p>You will require a modern <a href="http://www.wxpython.org/">wxPython</a>
and Python installation. &nbsp;The setup will create a script named
"runsnake" on Linux machines which launches the profile viewer.</p>
<h2><a name="usage"></a>Usage</h2><p>To use cProfile to capture your application's profile data:</p><pre>import cProfile<br>command = """reactor.run()"""<br>cProfile.runctx( command, globals(), locals(), filename="OpenGLContext.profile" )</pre><p>To view the results of your run:<br>
</p>
<pre>python runsnake.py OpenGLContext.profile<br></pre>
<p>There will be a brief delay as the application is created and begins
the loading process, then you should see something like this:</p>
<p style="text-align: center;"><img style="width: 1113px; height: 872px;" alt="Screenshot of the application viewing a HotShot profile" src="screenshot-2.0.png"><br>
</p>
<p>Click on any column title to sort by that property within that list.
&nbsp;Select a record in the left-most list view to see a breakdown of
that record in the right-side list views. &nbsp;Choose the appropriate
view on the right via the tabs. &nbsp;You can resize the borders
between the lists and square-map views. &nbsp;You can select a
package/module/function hierarchic view via the menus. &nbsp;You can
also toggle use of percentage displays there.</p><h2><a name="code"></a>Code Access and Contributions</h2><p>RunSnakeRun
is reasonably stable. &nbsp;I don't tend to do much work on it, as it
tends to just work. &nbsp;My current wish list for the project follows:</p><ul><li>allow
for loading-and-comparing two runs in a data-grid side-by-side with the
equal functions next to each other (blanks for functions that don't
exist in both runs)</li><ul><li>allow for tracking and comparing functions across multiple runs</li></ul><li>re-enable loading of Hotspot profiler runs</li><li>add an lsprofcall loader (should be trivial, cProfile/profile is the same basic data just in a different format)</li><li>storage of preferences such as column widths</li><li>utility functions for capturing data</li></ul><p>If you have an idea, feel free
to check out the code and&nbsp;implement the new&nbsp;feature. &nbsp;I'm certainly willing
to entertain new features or bug-fix requests as well. &nbsp;The code
is available in bzr here:</p><pre>bzr branch lp:~mcfletch/squaremap/trunk squaremap<br>bzr branch lp:~mcfletch/runsnakerun/trunk runsnakerun<br>cd runsnakerun<br>python setup.py develop<br></pre><p>You can <a href="mailto:mcfletch@vrplumber.com">contact me directly</a> if you'd like to contribute. &nbsp;Or you can just set up a bzr branch on LaunchPad and request a merge.</p><h2><a name="roadmap"></a>Roadmap/Wish-list</h2><p>This is just a listing of things that either I or others have requested as features:</p><ul><li>provide comparison views and "progress" views that compare across multiple profiles</li><li>(re)support&nbsp;Hotshot profile dumps (removed because Hotshot itself was deprecated)</li><li>support&nbsp;Robert Kern's line_profiler module</li><li>support&nbsp;(C) lsprof files (as used by kcachegrind)</li><li>support&nbsp;IronPython profiles (with cleanup on load to remove "noise" functions)</li><li>with a line-profiling module, allow per-line profile views</li><li>rework squaremap to be more robust for large profiles</li><li>clean up the UI code (very hacky)</li></ul>
<h2><a name="download"></a>Releases/Downloads</h2>
<ul>
  <li>2.0.0b4 -- Win32 bug-fixes, drawing of labels on squaremap where there's enough space</li><li><a href="http://pypi.python.org/packages/source/R/RunSnakeRun/RunSnakeRun-2.0.0b1.zip">2.0.0b1</a> -- packaging fixes, UI fixes</li><li>2.0.0a1 -- Eliminate support for (obsolete) Hotshot
profiles, add squaremap visualization and callee/caller views, lots of
UI work to make the application more usable, preliminary i18n work
(just gettext markup)</li><li><a href="RunSnakeRun-1.0.4.tar.gz">1.0.4</a> -- Add
preliminary support for standard cProfile/profile profile results, note
that we do not load cProfile results incrementally. &nbsp;Switch to
numpy support from Numeric. &nbsp;Use setuptools for distribution.
&nbsp;Provide source repository access.</li><li><a href="RunSnakeRun-1.0.3.tar.gz">1.0.3</a> -- Fix stupid bug
introduced by last fix</li>
  <li><a href="RunSnakeRun-1.0.2.tar.gz">1.0.2</a> -- Magically grow
the stack-tracking structures if we pass recursion limits, this will be
slow, but it should allow for loading even extremely stack-exhausting
programs</li>
  <li><a href="RunSnakeRun-1.0.1.tar.gz">1.0.1</a> -- Bug-fix,
increases stack-tracking size to 10x recursion limit, instead of ==
recursion limit, but as of yet, doesn't seem to fix the reported
stack-exhaustion</li>
  <li><a href="RunSnakeRun-1.0.0.tar.gz">1.0.0</a> -- Initial release,
no fancy features, just the raw functionality</li>
</ul>
<p class="footer">Copyright 2005-2009 Mike Fletcher<br>
</p>
</body></html>